Date: December 2, 1992
From: Jamshid Afshar (jamshid@ccwf.cc.utexas.edu)
Subject: JCOOL 0.1 -- A free C++ class library using templates


INTRODUCTION:

This is the README file for JCOOL 0.1.  This file and the JCOOL
library are available by anonymous ftp at cs.utexas.edu in the
directory pub/COOL as the files JCOOL01.TXT and JCOOL01.ZIP.  JCOOL
is a modified version of GECOOL 2.1 (also available at cs.utexas.edu
in pub/COOL/GECOOL2.1.tar.Z). GECOOL 2.1 is a reworking and
enhancement of Texas Instrument's "C++ Object Oriented Library" (at
csc.ti.com in ~ftp/pub/COOL.tar.Z) by some programmers at General
Electric.  See the file 'coolhist' for more information about the
history of COOL and its spinoffs.

JCOOL's main difference from COOL and GECOOL is that it uses real C++
templates instead of a similar syntax that is preprocessed by a
special 'cpp' distributed with COOL and GECOOL.  Of course, this
means JCOOL can only be compiled with a compiler implementing
templates.  I named the library JCOOL so as not to confuse it with
other current or future versions and spinoffs of COOL.  Hopefully any
further work will be merged to create a freely available and usable,
portable general C++ class library.  JCOOL includes the classes
AVL_Tree, Association, Bignum, Binary_Tree, Bit_Set, Complex,
Date_Time, Envelope, Gen_String, Handle, Hash_Table, Iterator, List,
M_Vector, Matrix, N_Tree, Pair, Quaternion, Queue, Random, Range,
Rational, Regexp, Set, Shared, Stack, String, Timer, Value, Vector.
Most of these are class templates.  So far JCOOL has only been
compiled under Borland C++ 3.1.


PURPOSE:

C++ is a powerful tool but its major benefits cannot be achieved, nor
can a new user be productive, without a good data structures
library.  While I hope JCOOL eventually leads to something any C++
user can confidently start with or incorporate into their existing
code, this version of JCOOL is 0.1 to reinforce the fact that it is
far from being fully tested or stable.  Some of the tests and
examples fail either because of bugs in the code or the compiler.
This library is provided without warranties of any kind.

My main goal in releasing it now is to improve the overall quality of
C++ compilers, especially with respect to templates.  I found (and
reported) numerous BC++ bugs in the process of building JCOOL. Please
try to compile it on any C++ compiler claiming to support templates
and (loudly) report the bugs that will inevitably pop up.  While I do
have a long "todo" list of bug fixes and enhancements, and I do want
to be kept abreast of any work, I will probably not have time to do
much work on JCOOL in the near future. I am also somewhat worn out
after fighting BC++ 3.1 over the past several months (though I'm sure
Borland loves me :-).  I will be eager to enhance JCOOL once a new,
more bug-free version of BC++ is released.  Please don't let this
disclaimer keep you from sending comments or suggestions.  I'm always
interested in bug reports, fixes, or suggestions on improving this
package.  Please also consider letting others know about bugs or
ports by posting to comp.lang.c++.


DIRECTIONS:

Get the file pub/COOL/JCOOL01.ZIP by anonymous ftp at cs.utexas.edu. 
It will unzip into:
   cool/
      tests/ - test programs, makefile for tests
      examples/ - example programs, makefile for examples
      readme - *this file
      todo - bugs, plans
      changes - changes, including GECOOL changes from COOL
      makefile - Borland C++ 3.1 makefile to create cool.lib
      coolhist - a COOL history report courtesy of Mary J. Fontana
      renlong.sh - renames all files to their original UNIX names
      renshort.sh - renames all files to DOS (8.3) names
      *.h
      *.c

The makefile assumes you have BC++ 3.1 installed in c:\borlandc.  The
large memory model is used.  Please read 'todo' and 'changes' before
using JCOOL as they mention bugs I've encountered.  After modifing
'makefile' if necessary, do the following to install into your
D:\FREELIBS directory and compile your program MYPROG.CPP.

   D:\FREELIBS>unzip -d JCOOL01  => creates COOL directory
   D:\FREELIBS\COOL>make         => creates COOL.LIB
   D:\FREELIBS\COOL\TESTS>make runall.out => creates test*.exe and runs them
   D:\FREELIBS\COOL\EXAMPLES>make runall.out => creates ex*.exe and runs them
   C:\MYPROG>bcc -Ic:\borlandc\include;d:\freelibs;d:\freelibs\cool
                 -ml -vi- -w -w-sig -w-amp
                 myprog.cpp d:\freelibs\cool\cool.lib  => creates myprog.exe

See the TESTS and EXAMPLES directories for sample code and see the
header files themselves for class documentation.  You should include
JCOOL headers by specifying the 'cool' path (eg, #include
<cool/Binary_Tree.h>). Doing so allows you to use JCOOL with other
libraries containing the same file names.  Use the full,
case-sensitive file name so that your code is portable to less
restrictive file systems.  You should #include the .C file of
template classes in one of your modules (see the BC++ docs for more
information about template instantiation).


ACKNOWLEGEMENTS:

Thanks to the following for all their work on the design and
implementation of COOL and GECOOL, and for making their work freely
available.

      Mary J. Fontana (fontana@mtc.ti.com)
      Van-Duc Nguyen (nguyen@crd.ge.com)
      LGO?
      DLS?
      MBN?

A general thanks to the USENET community, especially comp.lang.c/c++,
for being a wealth of information and ideas.

Finally, a special thanks to my s.o. Walter for putting up with my
all-nighters at the office working on this and other C++ projects.


SHAMELESS PLUG/PLEA:

Btw, if you are in the Austin area and looking for an expert C++
programmer with 3 years work experience under DOS/MS-Windows and the
ability to quickly learn other environments, please contact me for a
resume.


DISCLAIMERS:

//
// Copyright (C) 1991 Texas Instruments Incorporated.
//
// Permission is granted to any individual or institution to use, copy, modify,
// and distribute this software, provided that this complete copyright and
// permission notice is maintained, intact, in all copies and supporting
// documentation.
//
// Texas Instruments Incorporated provides this software "as is" without
// express or implied warranty.
//


CONTACT:

Jamshid Afshar
Email: jamshid@ccwf.cc.utexas.edu or jamshid@emx.utexas.edu
USMail: 401 E. 4th Street #403, Austin, TX 78701
USPhone: (512) 474-7455